machine/esp32: add PWM support using the LEDC peripheral for classic esp32 board - #5669

Why

The classic ESP32 is the only ESP32 chip in TinyGo without PWM. This adds it.

It uses the high speed half of the LEDC peripheral. This gives 4 timers
(PWM0 to PWM3) and 8 channels. You can use any pin, because the signal goes
through the GPIO matrix.

This closes the ESP32 part of #5186. Thanks to @jespino for the first version
and for the hardware research. His register values were a good check while I
wrote this.

What changed

The C3 and the S3 have LEDC PWM. Most of machine_esp32xx_pwm.go is the same
for all of these chips. This change uses that code again. It does not add a
second driver for the same peripheral.

Three functions in that file work only on the newer chips. They move to a file
for each chip.

The files are now:

machine_esp32xx_pwm.go       esp32 || esp32c3 || esp32s3   shared code
machine_esp32xx_ls_pwm.go    esp32c3 || esp32s3            new, moved code
machine_esp32c3_pwm.go       esp32c3                       invert case removed
machine_esp32s3_pwm.go       esp32s3                       invert case removed
machine_esp32_pwm.go         esp32                         new

machine_esp32xx_ls_pwm.go holds code that moved out of the shared file. In the
first commit that code is unchanged, so the C3 and the S3 keep their behaviour
and their binaries. The second commit then edits it, along with the two per chip
files, for the fixes listed below.

This also adds src/examples/pwm/esp32-coreboard-v2.go and one line in the
smoketest-esp target.

Why these decisions

Why this is not a change to #5186.

That PR is older than the esp32xx shared layer from #5215. It adds a type of
its own in one file of 601 lines. The tree would then have two LEDC drivers.
One uses the generated SVD setters. The other uses register offsets and masks
written by hand. The shared type keeps one driver. It also checks the register
names against the description from Espressif.

Why the high speed block.

This chip has a high speed block and a low speed block. High speed channels
apply a duty change themselves at the end of the period. There is no glitch and
no PARA_UP bit to set. The low speed block can come later if somebody needs
the 8 more channels.

Why a new file and not a change to the shared file.

TICK_SEL has the opposite meaning on this chip.

ESP32 high speed timers   1 = APB_CLK 80MHz   0 = REF_TICK 1MHz
C3 and S3 low speed       the shared code writes 0

A shared setTimerConf would select the 1MHz clock on the ESP32. All
frequencies would then be 80 times too slow. A file for each chip prevents
this.

Why the C3 and S3 still use a long switch.

The ESP32 chanOp finds its register with pointer arithmetic, because the
channel registers repeat every 0x14 bytes and outFunc in machine_esp32.go
already works that way. The C3 and S3 registers repeat too, so the same change
would suit them, but it would rewrite files this PR only needs to touch for the
fixes. That is a good follow up.

Why GPIO18 and GPIO19 in the example.

These pins have no function at boot. They also do not go to an LED on the
board.

MCPWM is not in this change. Motor control PWM is a different peripheral. It
needs dead time and fault inputs, so it needs a different API.

Fixes in the shared code

These are older than this PR, but the ESP32 support makes them reachable. Most
came out of review.

The four timers share the eight channels. Each LEDCPWM had its own channel
table starting at index 0, so PWM0.Channel(a) and PWM1.Channel(b) both
returned channel 0 and both wrote hardware channel 0. The table now belongs to
the peripheral and records which timer owns each entry.

Configure cleared the whole table, which with a shared table erases the
channels of the other timers. It now releases only its own, and a released
channel also stops driving its pin, because the table alone does not stop the
hardware.

Set and SetInverting took a channel number without checking the owner.
One timer could reprogram another timer's channel with the duty scaled for the
wrong resolution. Both now go through LEDCPWM.owns.

SetInverting did not invert. It wrote IDLE_LV, which only sets the pin
level when SIG_OUT_EN is 0. The GPIO matrix does the inversion with INV_SEL
in FUNCn_OUT_SEL_CFG, and the SVD already gives that bit for each chip.
chanOp no longer has an invert operation.

enableClock pulsed the LEDC reset on every Configure, which clears every
timer and channel. It now runs once on all three chips. It also runs before the
period is checked, so a call returning ErrPWMPeriodTooLong used to destroy
every running output on its way out.

A period above one second divided by zero. freq truncates to 0 and the
divider panics. Configure returns ErrPWMPeriodTooLong.

Tests

• gofmt
• Builds for esp32-coreboard-v2, esp32-generic, esp32c3-generic,
  esp32c3-supermini, esp32s3-generic and xiao-esp32s3
• After the first commit the examples/pwm binaries for
  esp32c3-supermini and xiao-esp32s3 are byte for byte identical to
  dev. The second commit changes them on purpose
• Tested on an ESP32-WROVER board

On that board the four timers now return channels 0, 1, 2 and 3 for four pins,
where before they all returned channel 0. Configuring a second timer leaves the
channel of the first one untouched. With the duty at the top a pin reads 100
percent high, SetInverting makes it 0 percent, and switching it off again
returns it to 99 percent.

A pin driven at full duty reads 0 percent after a second Configure releases
its channel. A Set from a timer that does not own the channel leaves the
output at 100 percent. A Configure with a period of 2 seconds returns
pwm: period too long instead of panicking. Writing a different value to all 4
timers and all 8 channels through the new pointer arithmetic, then reading each
back through the named registers, gives the same values.

A servo on GPIO15 turns from 0 to 180 degrees and back. The movement is smooth.
A servo moves only with pulses between 0.5ms and 2.5ms that repeat near 50Hz. A
wrong divider puts the arm in the wrong place. A wrong duty stops the movement.

One known limit

The shared Configure cuts the clock divider to a whole number.

divActual = 80_000_000 / (freq << dutyRes)

At 50Hz with 14 bit resolution this is 97.66, and the code uses 97. The
period is then 19.87ms and not 20ms. Pulses are about 0.67% too short.

This is the behaviour that the C3 and the S3 have now. This change does not add
it. A divider that rounds to the nearest number would give about 0.35%. That
changes the output of all three chips, so it belongs in its own PR.